package cn.cyh.queue_service.service;

import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.TimeUnit;

/**
 * 缓存服务接口，封装Redis操作
 */
public interface CacheService {
    
    /**
     * 设置缓存
     *
     * @param key 缓存键
     * @param value 缓存值
     */
    void set(String key, Object value);
    
    /**
     * 设置缓存并设置过期时间
     *
     * @param key 缓存键
     * @param value 缓存值
     * @param timeout 过期时间
     * @param unit 时间单位
     */
    void set(String key, Object value, long timeout, TimeUnit unit);
    
    /**
     * 获取缓存
     *
     * @param key 缓存键
     * @param <T> 返回类型
     * @return 缓存值
     */
    <T> T get(String key);
    
    /**
     * 删除缓存
     *
     * @param key 缓存键
     * @return 是否删除成功
     */
    boolean delete(String key);
    
    /**
     * 批量删除缓存
     *
     * @param keys 缓存键集合
     * @return 删除的键数量
     */
    long delete(Collection<String> keys);
    
    /**
     * 设置过期时间
     *
     * @param key 缓存键
     * @param timeout 过期时间
     * @param unit 时间单位
     * @return 是否设置成功
     */
    boolean expire(String key, long timeout, TimeUnit unit);
    
    /**
     * 判断键是否存在
     *
     * @param key 缓存键
     * @return 是否存在
     */
    boolean hasKey(String key);
    
    /**
     * 获取过期时间
     *
     * @param key 缓存键
     * @param unit 时间单位
     * @return 过期时间
     */
    long getExpire(String key, TimeUnit unit);
    
    /**
     * 递增
     *
     * @param key 缓存键
     * @param delta 增加的值
     * @return 增加后的值
     */
    long increment(String key, long delta);
    
    /**
     * 递减
     *
     * @param key 缓存键
     * @param delta 减少的值
     * @return 减少后的值
     */
    long decrement(String key, long delta);
    
    /**
     * 获取匹配的键
     *
     * @param pattern 匹配模式
     * @return 匹配的键集合
     */
    Set<String> keys(String pattern);
    
    /**
     * 列表操作 - 左推入
     *
     * @param key 列表键
     * @param value 值
     * @return 列表长度
     */
    long leftPush(String key, Object value);
    
    /**
     * 列表操作 - 右推入
     *
     * @param key 列表键
     * @param value 值
     * @return 列表长度
     */
    long rightPush(String key, Object value);
    
    /**
     * 列表操作 - 左弹出
     *
     * @param key 列表键
     * @param <T> 返回类型
     * @return 弹出的值
     */
    <T> T leftPop(String key);
    
    /**
     * 列表操作 - 右弹出
     *
     * @param key 列表键
     * @param <T> 返回类型
     * @return 弹出的值
     */
    <T> T rightPop(String key);
    
    /**
     * 列表操作 - 获取列表长度
     *
     * @param key 列表键
     * @return 列表长度
     */
    long listSize(String key);
    
    /**
     * 列表操作 - 获取列表范围
     *
     * @param key 列表键
     * @param start 开始索引
     * @param end 结束索引
     * @param <T> 返回类型
     * @return 列表范围内的值
     */
    <T> List<T> listRange(String key, long start, long end);
    
    /**
     * 获取分布式锁
     *
     * @param lockKey 锁的键
     * @param requestId 请求标识
     * @param expireTime 锁过期时间
     * @param timeUnit 时间单位
     * @return 是否获取成功
     */
    boolean tryLock(String lockKey, String requestId, long expireTime, TimeUnit timeUnit);
    
    /**
     * 释放分布式锁
     *
     * @param lockKey 锁的键
     * @param requestId 请求标识
     * @return 是否释放成功
     */
    boolean releaseLock(String lockKey, String requestId);
    
    /**
     * 哈希操作 - 设置哈希表字段
     *
     * @param key 哈希表键
     * @param hashKey 字段键
     * @param value 字段值
     */
    void hashSet(String key, String hashKey, Object value);
    
    /**
     * 哈希操作 - 获取哈希表字段
     *
     * @param key 哈希表键
     * @param hashKey 字段键
     * @param <T> 返回类型
     * @return 字段值
     */
    <T> T hashGet(String key, String hashKey);
    
    /**
     * 哈希操作 - 删除哈希表字段
     *
     * @param key 哈希表键
     * @param hashKeys 字段键
     * @return 删除的字段数量
     */
    long hashDelete(String key, Object... hashKeys);
    
    /**
     * 哈希操作 - 判断哈希表是否有该字段
     *
     * @param key 哈希表键
     * @param hashKey 字段键
     * @return 是否存在
     */
    boolean hashHasKey(String key, String hashKey);
    
    /**
     * 哈希操作 - 获取哈希表所有字段
     *
     * @param key 哈希表键
     * @return 所有字段
     */
    Map<Object, Object> hashEntries(String key);
} 